
                            Broadcom Corporation
              
                               Release Notes
                              
                  Broadcom NetXtreme Firmware Upgrade Tool
                                 for Linux
                         
                Copyright (c) 2005-2017 Broadcom Corporation
                            All rights reserved.
                               Apr 10, 2017


Table of Contents
=================
    1. Introduction
    2. Requirements
    3. Installation
    4. Command Usage
    5. Exit Codes
    6. Examples
    7. Known Limitations
    8. Disclaimer
    9. Third Party Software License

1. Introduction:
================

This utility is a console application which can be run from a Linux 
command prompt. The application will use the console to interact with 
the users.

When calling the utility from another process or when using the utility 
as a command line tool, the utility will take commands from user specified
parameters and return appropriate exit code to indicate the result. 

This module is dependent on device driver, BMAPI module, and TCL libraries 
for firmware access.


2. Requirements:
================

     1.  Driver Versions: 
         tg3 Linux driver version 3.58b or above

         Please refer to README.TXT of the target driver for installation 
         instruction.

     2.  BMAPI version: 
         bmapilnx 6.3.41 or above.

     3.  For v2.2.1 or later
         libncurses.so.5 and libtinfo.so.5 are needed.
         Please use 'ldd lnxfwupg' to find the dependency of these libraries.


3. Installation:
================

     1.  To install lnxfwupg SDK package. 

         a.  Please do 'tar -zxvf lnxfwupg-{arch}.sdk.tgz' to untar the 
             package. 
 
             The files included in the sdk package are:
             1)  lnxfwupg                       -  This upgrade utility program
             2)  Readme.txt                     -  This file.
             3)  Release.txt

     2.  To install BMAPI library SDK package: 

         a. Do 'tar -zxvf bmapilnx-{version}.sdk.tgz' to untar the package
            in the same directory.

             The files included in the sdk package are:
             1)  bcmtype.h                     
             2)  BMAPI.h                   
             3)  brcm_pci.ids
             4)  BMAPILNX library
                 - For x86 platforms: 
                   libbmapi.so.{version}        BMAPI 32-bit shared library 

                 - For x86_64 platforms: 
                   libbmapi_x64.so.{version}    BMAPI 64-bit shared library 
                   libbmapi.so.{version}        BMAPI 32-bit shared library 

                 - For PPC64 platforms: 
                   libbmapi_ppc64.so.{version}  BMAPI 64-bit shared library for PPC

           
4. Command Usage:
=================
  
Usage:
  lnxfwupg [ -all | [ID | MAC] ] [Commands]
    The '-all' option applies to 'upgrade', 'autoupg' and 'restorenvram' commands
    only. 

    The ID/MAC is optional for 'help', 'version', and 'dev'
    commands, but it is required for all other commands.

    1. When '-all' is specified, 'ID' or 'MAC' cannot be specified.
       'upgrade', 'autoupg' and 'restorenvram' commands will use the device
       information in the image to apply to all NICs that match the
       same device information. 

    2. On Linux, 'ID' is the the interface name (i.e. ethX). 

    3. 'MAC' is the MAC address name of the NIC in the system. For example, 
       '00:10:18:00:11:99' is a valid MAC address from 'ifconfig' utility. 
       Use '001018001199' as an input parameter to select the NIC.

    Following is the list of available commands:
    help        : list of available commands
    q           : exit the program
    cfg         : Configure NVRAM
    dev         : select an adapter or List available adapters
    dir         : display file directory in NVRAM
    crc         : check/update NVRAM checksum
    prg         : Program NVRAM with specified firmware image
    dumpnvram   : save entire NVRAM content to a file
    restorenvram: restore entire NVRAM content from a file
    version     : display version of this program
    upgrade     : upgrades the firmware or bootcode
    autoupg     : automatically upgrades the firmware or bootcode as per configuration file.
    -w          : Enable/Disable WOL, deprecated, please use 'cfg -wol <value>'.


    cfg [-noreset] {-mac <MAC address to be programmed for current selected device> | 
         -mba <value> | -asf <value> | -ump <value> | -setman <t|p|m> |
         -mgmt <value> | -wol <value> | -aspm <value> | -tph <value> |
         -vpdv0 <version string> | -show}
        This command programs the specified configuration into NVRAM.

        The -noreset option is to skip the driver restart of the selected
        NIC after the cfg command is completed.  This option is only
        valid in Command Line Mode.
        -mac        : <MAC address for current selected device> is a 
                      12-digit HEX MAC address, e.g. 0010181a2b3c.
        -mba        : set <value> to '1' to enable mba firmware.
                      set <value> to '0' to disable mba firmware.
        -asf        : set <value> to '1' to enable asf firmware.
                      set <value> to '0' to disable asf firmware.
        -ump        : set <value> to '1' to enable ump firmware.
                      set <value> to '0' to disable ump firmware.
        -setman     : set APE active management firmware.
                    t: toggle APE active management firmware.\r\n"
                    p: activate Inactive APE management firmware if it's PASSTHRU.\r\n"
                    m: activate Inactive APE management firmware if it's TruManage.\r\n"
        -mgmt       : set <value> to '1' to enable management firmware.
                      set <value> to '0' to disable management firmware.
        -wol        : set <value> to '1' to enable wol feature.
                      set <value> to '0' to disable wol feature.
        -aspm       : set <value> to '1' to enable L1 ASPM debounce feature.
                      set <value> to '0' to disable L1 ASPM debounce feature.
        -tph        : set <value> to '2' to advertise TPH with ST mode
                      set <value> to '1' to advertise TPH without ST mode
                      set <value> to '0' to disable TPH feature
        -vpdv0      : set <version string> to VPD V0 tag.
                      <version string> can be within "" to include space char.
	-vpdyb      : set <user string> to VPD
        -show       : show the settings of current configuration.
        -show vpdv0 : display value of VPD V0 in NVRAM.
        -show vpdyb : display value of VPD YB in NVRAM.

    dev [<number>]
        <number> is the adapter to be selected as target device

    dir [-delete <type>]
        Displays a listing of the firmware programmed in NVRAM.
        Delete the specified <type> in the directory and its firmware from NVRAM.
        The FwUpg tool will return successfully if the firmware is not existing.
        The <type> is the type of firmware to be deleted.

        The keyword strings used for the <type> are as following:
            MBA: MBA/PXE
            ASFINIT: ASF Init
            ASFCPUA: ASF CPUA
            ASFCPUB: ASF CPUB
            ASFCFG: ASF CFG
            ISCSICFG: iSCSI CFG for port 0
            ISCSIPRG: iSCSI CFG Program
            ISCSIBOOT: iSCSI Boot
            ISCSICFG1: iSCSI CFG for port 1
            APECFG: APE CFG
            APECODE: APE firmware
            APECODENA: Inactive APE firmware
            APEUPDATE: APE update firmware
            APEDATA: APE data
            APEWEBDATA: APE Web data
            APEWORKAROUND: APE Workaround
            EXTVPD: Extended VPD
            APEAUDITLOG: APE Audit Log
            APEEVENTLOG: APE Event Log
            ISCSICFG2: iSCSI CFG for port 2
            ISCSICFG3: iSCSI CFG for port 3
            CCM: CCM firmware
 		
    crc 
        Checks the integrity of the NVRAM CRC,

    prg {-ib|-mba|-ccm} {<new_image>} [-c] [-p]
        This command programs NVRAM with the specified firmware image.
		This command is used to program firmwares that are not already 
		present in the nvram.
        -ib        : iSCSI boot firmware
        -mba       : MBA firmware
        -ccm       : CCM firmware
        <new_image>: a mandatory parameter to specify the input binary file.
        -c         : force to program iSCSI configuration, only valid when
                     used with -ib option.
        -p         : force to program iSCSI configuration utility program,
                     only valid when used with -ib option.
        Note: 'prg' command only supports selective Broadcom adapters.

    dumpnvram {<filename>}
        Dumps the NVRAM contents to the specified file.
        <filename> is a mandatory parameter. Use forwardslash instead of 
        backslash when specifying <filename>. Alternatively you could also 
        use two backslashes in the file path.

    restorenvram {<filename>} [idmatch] [config [mac]] [preserve [mac] [bmac]]
        This command reads complete NVRAM image from a file and
        writes the image to NVRAM.
        Before writing the NVRAM image to adapter, verifications
        against source NVRAM image will be performed. If any verification
        failed, the image will not be written to adapter.
        <filename> is the file name of NVRAM image that was dumped from the NIC.
        <filename> is a mandatory parameter. 
        'idmatch' requests the Firmware Upgrade Tool to restore the NVRAM
        image only after the 4 IDs (vendor_id, device_id, subsystem_vendor_id,
        subsystem_device_id) in the image file match those in the device.
        This is on top of all previous criteria that have to be met.
        'config' means configuration area will copy from source
        image except MAC address.
        Configuration area includes MAC address and various
        options.
        'mac' applies only when 'config' is specified.
        When 'mac' is specified, all configuration are copied
        including MAC address.
        'preserve' means configuration area will be copied from
        the source image except for the parameters supplied
        after this command. Configuration area includes MAC
        address, backup MAC address and various other options.
        'mac' is applicable with 'preserve' option.
        When 'mac' is specified, MAC address is preserved.
        'bmac' is applicable only when 'preserve'option is specified.
        When 'bmac' is specified, backup MAC addresses
        are preserved.

    version
        displays version of this program.
    
    upgrade [-noreset] [-F] 
        {-bc|-mba|-asf|-ump|-mgmt|-mgmt_ia|-ib|-ib_ipv6|-ib_ipv4n6|-vpd|-usr|-ccm}
        [-c] [-p] {<filename>} [<savefile>]
        This command upgrades the firmware or bootcode for
        the NetXtreme controller. This command will only upgrade 
		or downgrade on any existing firmware. To program firmwares 
		that are not already present in the nvram please use the 
		prg command. The <filename> specifies the name of the file 
		that contains the appropriate image.
        The <savefile> specifies the name of the file to which the
        current NVRAM contents will be saved.  If <savefile> is not
        specified, the current NVRAM contents will not be saved.
        Both <filename> and <savefile> are mandatory parameters.
        Use forwardslash instead of backslash when specifying file path.
        Alternatively you could also use two backslashes in the file path.
        If the upgrade version is same or older than the version
        in NVRAM, upgrade will be aborted.
        The -noreset option is to skip the driver restart of the selected
        NIC after the firmware upgrade is completed.  This option is only
        valid in Command Line Mode.
        The -F option is to force the upgrade without checking version.
            OPTION           NAME OF FIRMWARE OR BOOT IMAGE
            -bc                bootcode
            -mba               MBA (PXE) firmware
            -asf               ASF firmware
            -ump               UMP firmware
            -mgmt              Management firmware
            -mgmt_ia           Inactive Management firmware
            -ib                iSCSI boot firmware
            -ib_ipv6           iSCSI boot firmware to support IPv6
            -ib_ipv4n6         iSCSI boot firmware to support IPv4 and IPv6
            -vpd               Extended VPD
            -usr               User block
            -ccm               CCM firmware
        The [-c], [-p] option is valid only when "-ib" option is specified.
            -c                 upgrade the iSCSI configuration along with iSCSI boot code.
                               The '-ib', '-ib_ipv6', and '-ib_ipv4n6' will add/upgrade the
                               iSCSI configuration automatically.
                               This option does not have effect any more.
            -p                 upgrade the iSCSI configuration program along
	                       with iSCSI boot code.

    autoupg [-noreset] [-F] 
        [-crc]  [-dir] {-cfg <full_path_config_file>}

        This command automatically upgrades the firmware or bootcode for
        the NetXtreme controller.  The <full_path_config_file> specifies
        the name of the configuration file that contains the list of adapters 
        which require upgrade along with the comma separated firmware lists.
        This is a required input and auto upgrade will not continue in absence
        of this file. 
       “autoupg” command is a wrapper upon “upgrade” command. It supports all 
        the following firmware types, supported by “upgrade” command.
	
            OPTION       NAME OF FIRMWARE OR BOOT IMAGE
            -bc                bootcode
            -mba               MBA (PXE) firmware
            -fmba              FCODE MBA  
            -asf               ASF firmware
            -ump               UMP firmware
            -mgmt              Management firmware
            -mgmt_ia           Inactive Management firmware
            -ib                iSCSI boot firmware
            -ib_ipv6           iSCSI boot firmware to support IPv6
            -ib_ipv4n6         iSCSI boot firmware to support IPv4 and IPv6
            -vpd               Extended VPD
            -usr               User block
            -ccm               CCM firmware	

            It also support following configuration option
            -vpdyb            replace the vpdyb field in NVRAM with user 
                              supplied string.

       Below is the example of the configuration file:-

           1659&14e4&1659: bc=ee5721c3.66,vpdyb= 0xab,mba=5721.bin,
           16f3: bc=ee5727c3.08, ncsi=nx1ncsi1.02,ccm=ccmv710.71,
           upgver: 2.3.1

       First entry mentions the Broadcom adapter’s device ID or combination of 
       device id, subsystem vendor id and subsystem device id, separated by ‘&’
       and strictly in same order.

       <device id>
       OR
       <device id>&<subsystem vendor id>&<subsystem device id>

       All three of above are 4 character hexadecimal format strings 
       representing corresponding Broadcom NX1 adapter properties. User will 
       need to supply two different rows for adapters having same device id but
       different configurations (e.g. 5719 QuadRunner Vs 5719 Grantley LOM).

       “bc” mentions the firmware type need to be upgraded. Both are separated
        by a ‘:’. User can provide different firmware list with comma separated
        entries.
       Each entry will be in following format.

       <DEVICE ID/ COMBINED ID>:  <firmware type= file name>

	Build Versioning Support: upgver field in configuration file can be
        used for maintaining build versioning.
        upgver is an optional field for maintaining upgrade build versioning 
        via auto upgrade. After upgrade, NVRAM build version is replaced with
        the one mentioned in configuration file. If this option is not specified
        in configuration file, auto upgrade skips copying version string into
        NVRAM.
        Do not use this field if NVRAM vpdv0 field is being used for storing any
        other user specific information.
        VPDYB Fix: For mustang adapters, VPDYB fix is required. vpdyb field in
        configuration file can be used for this purpose.
        Below is an example of mentioning vpdyb field in configuration file.

            1656&14e4&1805 : ncsi= nx1ncsi1.02,vpdyb= 0x4f 0x46 0x4d 0x45 0x41, 

        FCODE Support: While upgrading MBA, fcode image need to be used if it is
        present in NVRAM, otherwise MBA image without fcode is used. 
        Configuration file supports two mba parameters for mentioning following
        two different types of multi boot agents.
            mba      :    mba without fcode
            fmba     :    mba with fcode

        Both can be mentioned in configuration file. Auto upgrade will select
        one appropriately based upon fcode detection.

            5721&1234&5678 : mba=NonFcodeMbaFile,fmba=FcodeMbaFile,

        If the upgrade version is same or older than the version
        in NVRAM, upgrade will be aborted.
        The -noreset option is to skip the driver restart of the selected
        NIC after the firmware upgrade is completed.  This option is only
        valid in Command Line Mode.
        The -F option is to force the upgrade without checking version.

    reset
        reset the selected NIC.This command is only valid in Command Line Mode.

    -w {<value>}
        The function enables or disables WOL setting.
        <value> set to '1' to enable WOL.
        <value> set to '0' to disable WOL.


5. Exit Codes:
==============

/////////////////////////////////////////////////////////////////////////
// Return codes
#define FWUPG_OK                                0   // Upgrade firmware OK
#define FWUPG_QUIT                              1   // Quit program
#define FWUPG_PARAM_ERROR                       2   // Not correct parameters
#define FWUPG_NOT_CORRECT_TARGET                3   // Not applicable to this device. 
#define FWUPG_CANNOT_READ_NVRAM                 4   // Cannot read NVRAM
#define FWUPG_FAILED_GET_NVRAM_SIZE             5   // Cannot get NVRAM size
#define FWUPG_CANNOT_GET_HANDLE                 6   // Cannot get NIC handle
#define FWUPG_ADAPTER_NOT_FOUND                 7   // Adapter not found
#define FWUPG_CANNOT_LOCK_ADAPTER               8   // Cannot lock adapter
#define FWUPG_FAILED_GET_PXE_INFO               9   // Failed to get PXE
                                                    // information
#define FWUPG_FAILED_CREATE_NVRAM_IMAGE_FILE    10  // Failed to create NVRAM
                                                    // image file
#define FWUPG_FAILED_WRITE_NVRAM_IMAGE_FILE     11  // Failed to write to
                                                    // NVRAM image file
#define FWUPG_GET_CLOSE_EVENT                   12  // Get close event
#define FWUPG_FAILED_READ_NVRAM_FILE            13  // Failed to read NVRAM
                                                    // image file
#define FWUPG_INIT_FAILED                       14  // Initialization failed
#define FWUPG_UNSUPPORTED_BMAPI_VER             15  // BMAPI is too old
#define FWUPG_NIC_NOT_SUPPORTED                 16  // NIC is not supported
#define FWUPG_UNKNOWN_COMMAND                   17  // Unknown command
#define FWUPG_NVRAM_WRITE_FAILED                18  // NVRAM update failed
#define FWUPG_WRONG_NVRAM_FILE_SIZE             19  // NVRAM image file size
#define FWUPG_NVRAM_IMAGE_CHKSUM_FAILED         20  // NVRAM image file
                                                    // checksum failed
#define FWUPG_NVRAM_CHKSUM_FAILED               21  // NVRAM checksum failed
#define FWUPG_NVRAM_IMAGE_FILE_DEVID_MISMATCH   22  // device information or media 
                                                    // type in NVRAM image file
                                                    // does not match NIC
#define FWUPG_ASF_NOT_SUPPORTED_BY_BOOTCODE     23  // ASF is not supported by
                                                    // the bootcode firmware
#define FWUPG_ASF_NOT_SUPPORTED_BY_NIC          24  // ASF is not supported by
                                                    // the NIC hardware
#define FWUPG_DIR_FULL                          25  // No NVRAM directory entry
                                                    // available
#define FWUPG_INVALID_NVRAM_FILE                26  // Incorrect NVRAM file
                                                    // format
#define FWUPG_NVRAM_FULL                        27  // not enough NVRAM space
#define FWUPG_DIR_NOT_SUPPORTED                 28  // Directory is not
                                                    // supported by bootcode
#define FWUPG_NVRAM_CORRUPTED                   29  // NVRAM corrupted
#define FWUPG_DIR_NOT_FOUND                     30  // a directory entry is
                                                    // not found
#define FWUPG_DIR_UPDATE_FAILED                 31  // Update NVRAM directory
                                                    // failed
#define FWUPG_DIR_FOUND                         32  // a directory entry is
                                                    // found
#define FWUPG_CANNOT_READ_MEM                   33  // Cannot read NIC register
                                                    // or memory
#define FWUPG_MALLOC_ERROR                      34  // memory allocation error
#define FWUPG_FW_IMAGE_WRONG_VERSION            35  // wrong version of
                                                    // firmware image
#define FWUPG_FW_IMAGE_INVALID_ASF              36  // invalid asf image
#define FWUPG_READ_NIC_ASF_TABLE_FAILED         37  // failed to read ASF table
                                                    // from  NIC
#define FWUPG_UNSUPPORTED_NIC_ASF_TABLE         38  // version of ASF table on
                                                    // NIC is not supported
#define FWUPG_REBOOT_FAILED                     39  // unable to reboot machine
#define FWUPG_NOT_SUPPORTED_DRIVER              40  // the version of driver is
                                                    // too old
#define FWUPG_DRIVER_NOT_LOADED                 41  // driver is not loaded
#define FWUPG_FILE_TOO_BIG                      42  // file is too big
#define FWUPG_CANNOT_WRITE_MEM                  43  // Cannot write NIC
                                                    // register or memory
#define FWUPG_MGMT_FW_NOT_FOUND                 44  // Cannot find management 
                                                    // firmware
#define FWUPG_UMP_FOUND                         45  // UMP firmware exist
#define FWUPG_FAILED_TO_GET_VERINFO             46  // failed to get module
                                                    // version info
#define FWUPG_ERR_ENDOFFILE                     47  // unexpected end of file
                                                    // encountered.
#define FWUPG_INVALID_MEDIUM_TYPE               48  // The chip has an unknown
                                                    // medium type. Neither the
                                                    // board is copper nor
                                                    // serdes.
#define FWUPG_INVALID_OFFSET                    49  // invalid NVRAM offset.
#define FWUPG_FILE_ALREADY_EXISTS               50  // output file already
                                                    // exists.
#define FWUPG_NON_SELFBOOT_IMAGE                51  // Not a selfboot image.
#define FWUPG_BAD_MAGIC_VALUE                   52  // Bad magic value
#define FWUPG_BAD_PARITY_VALUE                  53  // Bad parity value
#define FWUPG_BAD_VPD_CHKSUM                    54  // Bad VPD checksum
#define FWUPG_BAD_CHIP_REV                      55  // Bad chip revision
#define FWUPG_VPD_DATA_MISSING                  56  // VPD data missing
#define FWUPG_NO_SELFBOOT                       57  // target not self boot 
                                                    // capable
#define FWUPG_LEGACY_TO_SELFBOOT                58  // Cannot upgrade firmware 
                                                    // from legacy to selfboot.
#define FWUPG_ZERO_SELFBOOT                     59  // upgfrm does not support 
                                                    // Format 0 Selfboot image 
                                                    // upgrade
#define FWUPG_UNSUPPORTED_FEATURE               60  // Feature not supported.
#define FWUPG_DIAG_FAILURE                      61  // diag failure
#define FWUPG_NO_BRCM_ADAPTER                   62  // No Broadcom network 
                                                    // adapter found!
#define FWUPG_FILE_DOES_NOT_EXIST               63  // File does not exist
#define FWUPG_UMP_NOT_SUPPORTED                 64  // ump not supported
#define FWUPG_MISSING_UMP                       65  // UMP config firmware is
                                                    // not loaded in NVRAM
#define FWUPG_CFG_VER_MISMATCH                  66  // UMP config version 
                                                    // mismatch
#define FWUPG_INVALID_ISCSI_IMAGE               67  // invalid ISCSI image
#define FWUPG_INVALID_UMP_IMAGE                 68  // invalid UMP image
#define FWUPG_INVALID_MBA_IMAGE                 69  // invalid MBA image
#define FWUPG_PRG_FAILED                        70  // programming NVRAM failed
#define FWUPG_BOOTSTRAP_UPDATE_FAILED           71  // bootstrap update failed
#define FWUPG_CMD_ALL_NOT_SUPPORTED             72  // '-all' option is not 
                                                    // supported in this context
#define FWUPG_UNSUPPORTED_PLATFORM              73  // Feature not supported on 
                                                    // this platform
#define FWUPG_MAC_PARAM_ERROR                   74  // Cannot override MAC on 
                                                    // multiple NICs.
#define FWUPG_INVALID_BOOTCODE                  75  // Not a valid bootcode file
#define FWUPG_INVALID_IPMI_FILE                 76  // Not a valid ipmi file
#define FWUPG_INVALID_DUMP                      77  // Invalid dump file.
#define FWUPG_INVALID_FORMAT                    78  // Invalid image/file format.
#define FWUPG_DIR_ENTRY_MISMATCH                80  // Mismatch in directory entries
#define FWUPG_MBA_MISMATCH                      81  // MBA directory entry mismatch
#define FWUPG_UMP_MISMATCH                      82  // UMP directory entry mismatch
#define FWUPG_IPMI_MISMATCH                     83  // IPMI directory entry mismatch
#define FWUPG_ISCSI_MISMATCH                    84  // ISCSI directory entry mismatch
#define FWUPG_ASF_MISMATCH                      85  // ASF directory entry mismatch
#define FWUPG_ISCSI_NOT_SUPPORTED               86  // ISCSI is not supported.
#define FWUPG_SPECIAL_UPGRADE_REQUIRED          87  // Special upgrade is required.
#define FWUPG_MISSING_CMD                       88  // No valid command was specified.
#define FWUPG_RESERVE1                          89  // Reserved message holder.
#define FWUPG_RESERVE2                          90  // Reserved message holder.
#define FWUPG_MISSING_ASF                       91  // ASF config firmware is
                                                    // not loaded in NVRAM
#define FWUPG_MISSING_IPMI                      92  // IPMI config firmware is
                                                    // not loaded in NVRAM
#define FWUPG_MISSING_MBA                       93  // MBA config firmware is
                                                    // not loaded in NVRAM
#define FWUPG_NO_DEV_ID                         94  // No device ID in NVRAM image file
#define FWUPG_SYSTEM_REBOOT                     95  // System Reboot required
#define FWUPG_INVALID_NCSI_IMAGE                96  // invalid NCSI image
#define FWUPG_MISSING_MGMT_FW                   97  // Missing management firmware in NVRAM
#define FWUPG_INVALID_PHY_IMAGE                 98  // Invalid PHY firmware file.
#define FWUPG_DRIVER_COMMUNICATE_ERROR          99  // Error in communicating to driver
#define FWUPG_FW_EXISTING_IN_NVRAM              100 // The firmware to be programmed is existing in NVRAM
#define FWUPG_FAIL_TO_GET_MAC_ADDR              101 // Failed to read MAC ADDR from the file
#define FWUPG_MGMTFW_NOT_SUPPORTED_BY_NIC       102 // Management firmware is not supported by the NIC
#define FWUPG_IMAGE_FILE_CRC_ERROR              103 // Image file CRC error
#define FWUPG_INVALID_L2T_IMAGE                 104 // invalid L2T image
#define FWUPG_CMD_ABORTED                       105 // Command aborted
#define FWUPG_PHY_FW_CORRUPTED                  106 // PHY firmware corrupted
#define FWUPG_UNKNOWN_EXT_PHY                   107 // Unknown external PHY
#define FWUPG_CANNOT_UPGRADE_TO_DIFF_FORMAT     108 // Can't upgrade to a different format
#define FWUPG_CANNOT_READ_OTP                   109 // Can't read to OTP
#define FWUPG_CANNOT_WRITE_OTP                  110 // Can't write to OTP
#define FWUPG_FAIL_TO_CREATE_EXT_DIR_ENTRY      111 // Failed to create Extended Directory entry
#define FWUPG_INVALID_BOOTCODE_IMAGE            112 // invalid Bootcode image
#define FWUPG_INVALID_IO_MODULE_IMAGE           113 // Invalid I/O Module file.
#define FWUPG_NCSI_MISMATCH                     114 // NCSI directory entry mismatch
#define FWUPG_DIAG_TEST_NOT_SUPPORTED           115 // Specified Diagnostic tests are not supported
#define FWUPG_DIAG_TEST_FAILED                  116 // Diagnostic test failed
#define FWUPG_CANNOT_UNLOCK_ADAPTER             117 // Cannot unlock adapter
#define FWUPG_IMAGE_FILE_SIG_ERROR              118 // Image file RSA signature error
#define FWUPG_32BIT_APP_IN_WOW64                119 // Can't run 32-bit application in 64-bit platform.
#define FWUPG_INVALID_MFW_IMAGE                 120 // Invalid MFW image
#define FWUPG_INVALID_CCM_IMAGE                 121 // invalid CCM image
#define FWUPG_CCM_NOT_SUPPORTED                 122 // CCM is not supported.
#define FWUPG_CCM_MISMATCH                      123 // CCM directory entry mismatch 
#define FWUPG_DIAG_TEST_NOT_SUPPORTED           124 // Specified Diagnostic tests are not supported 
#define FWUPG_DIAG_TEST_FAILED                  125 // Diagnostic test failed
#define FWUPG_AUTO_UPG_ERR                      201 // Error Auto upgrading

6. Examples:
==============
    Note:  
    The 'restorenvram' and 'upgrade' commands shall perform successfully
    for the specified adapter meeting ALL the following conditions:
    1) The device information of the adapter matches that in the image file. 
    2) The adapter currently supports the requested target firmware. 


6.1  Command Line Mode Examples:
*******************************

        'lnxfwupg' will enter interactive mode.

        'lnxfwupg upgrade -bc /tmp/new_bootcode /tmp/oldBoot' will upgrade 
    bootcode for the ONLY qualified adapter found.  The adapter parameter can 
    be omitted if ONLY ONE qualified adapter is found.

        'lnxfwupg 001018001199 upgrade -mba b57mmbae.nic /backup/oldPXE.bin'
    will upgrade PXE for the adapter with MAC 00:10:18:00:11:99.

        'lnxfwupg {8580CDDC-961B-4829-A80C-478D22DB7B3E} upgrade -F -asf asfv55
    old_image' will upgrade ASF for the adapter with the specified GUID.

        'lnxfwupg -all upgrade -F -ump /tmp/ump114 backupUMP' will force a 
    downgrade for all the BRCM 5714/15/80 adapters with existing UMP support.  
    When multiple applicable adapters are present, the MAC address of the adapter 
    is appended to the backup NVRAM image parameter filename.

        'lnxfwupg -all restorenvram /tmp/backup.bin config' 
    reads a complete NVRAM image from file 'backup.bin' and write the image 
    to NVRAM along with its configurations.  If 'config' parameter is left out, 
    only the image is written. This will only restore NVRAM images to those with 
    matching FW, with the exception to variations in version numbers.

        'lnxfwupg 0010181a1b1c cfg -mac 0010189d9e9f' will configure the selected 
    adapter whose current MAC address is 00:10:18:1a:1b:1c to be the new MAC address
    00:10:18:9d:9e:9f.

        'lnxfwupg 0010189a9b9c cfg -asf 1' will enable asf firmware if the asf 
    firmware is present in the selected adapter whose current MAC address is 
    00:10:18:9a:9b:9c.
    
        'lnxfwupg –all autoupg –F –crc –dir –cfg /tmp/config.txt' will upgrade all matching
     adapters for all mentioned firmwares in configuration file.It will also run 'dir' and 'crc' commands on
     matching adapters.


6.2  Interactive Mode Examples:
*******************************

        'help' will display a list and descriptions of available commands.

        'q' will exit the utility.

        'dev' will display a list of upgradeable devices.

        'dev 0' will select device 0.

        'dir' will display a listing of the firmware programmed in NVRAM.

        'crc' will check the integrity of the NVRAM CRC.
 
        'dumpnvram /tmp/backup.bin config mac' will include all configurations
    including the MAC address and saves the dump file to the c drive.
    
        'restorenvram /tmp/backup.bin" config mac' will include all 
    configurations including the MAC address.  In order to verify the MAC 
    address was configured, exiting the program will be necessary followed 
    by either disabling and enabling the adapter or rebooting the system.
    
        'upgrade -bc ee5755c3.19 backup5755.bin' will upgrade the boot code 
    for a BRCM 5755 adapter.

        'version' will display the version of Firmware Upgrade utility. 

        '-w 1' will enable the WOL setting on the current adapter.

        'cfg -mac 0010181a2b3c" will configure MAC address for the selected
    qualified adapter.

        'cfg -ump 0' will disable ump firmware if the ump firmware is present
    in the selected adapter.

        'dir -delete MBA' will delete the MBA firmware from NVRAM.

        'dir -delete APEUPDATE' will delete APE UPDATE firmware from NVRAM.


    Examples for Deprecated Commands:
    *********************************
    Note: These deprecated commands are kept to be backward compatible with
          earlier releases.

        'seprg -a a25755c7.09 backupASF.bin' will upgrade/program ASF on a
    5754/5755/5786/5787.  If no save_image parameter is specified, ASF 
    will be upgraded without a backup NVRAM image.

        'asfprg asfe5ini.bin asfe5cpa.bin asfe5cpb.bin' will upgrade asf on a 
    5705 adapter. If no parameters are specified after 'asfprg' it will 
    automatically search within the same location as lnxfwupg for the files.

        'log log.txt' will create a text file 'log.txt' which will capture 
    all output and entered input.

         When using log in command mode, log file name should be of .log format


7. Known Limitations:
=====================

  1.  The read/write NVRAM operations for this utility are done through 
      the APIs provided by BMAPILNX. Consequently, its ability to support 
      Redhat EL3.0 is impacted by the "Known Limitations" as documented 
      in BMAPILNX readme.txt (see the following extracted note). In summary, 
      all commands requiring NVRAM access are unable to perform correctly on 
      Red Hat EL3.0 with kernel versions prior to 2.4.23.

      "Known Limitations" extracted from BMAPILNX readme.txt:

        Due to a limitation in kernel versions prior to 2.4.23, older
        Linux distributions including Red Hat EL 3.0 may cause BMAPI
        not function with error code 58 to indicate BMAPI_EEPROM_CORRUPTED.
        This problem is seen on 32-bit and 64-bit platforms with 57xx 
        family NICs loaded with tg3 driver (version >= 3.37) and 5706 
        family NICs loaded with bnx2 driver.
  
  2.  The current version of this tool has been tested on Red Hat 4, SuSE 9, 
      SuSE 10, Mandriva 2006, and Turbo 11 for i386, x86_64, and PowerPC CPU 
      architectures using 2.6.x kernels. 

  3.  The '-all' option is available in releases >= v1.0.3.

  4. When the Out-Of-Box tg3 driver is loaded, tg3 communication with the host tools fails
     if the NIC interfaces are DOWN. User needs to bring the NIC interfaces UP using the
     command "ifconfig <interface_name> up"

  5. In Linux OS, Firmware upgrade fails with the inbox driver loaded if the secure boot
     is enabled or the kernel configuration parameter CONFIG_IO_STRICT_DEVMEM=y is enabled.
     This is because the tools cannot map the BAR to access the hardware when these security
     features are enabled in the OS. In this case, The user has to load the out-of-box driver.

8. Disclaimer:
================ 

This version of the Linux Firmware Upgrade Utility has been validated only 
against the software component versions specified in the swdep.txt file.  
The Firmware Upgrade utility has not been qualified with other versions of 
the software components.  Using other software component version combinations 
has the potential to corrupt your NVRAM, resulting in an unusable network 
controller.  For this reason, Broadcom recommends that the software component 
versions listed in the swdep.txt file be used whenever possible.

9. Third Party Software License:
================================
Portions of this software contain third party code subject to the following conditions:

OpenSSL

/* ====================================================================
 * Copyright (c) 1998-2007 The OpenSSL Project.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. All advertising materials mentioning features or use of this
 *    software must display the following acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
 *
 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
 *    endorse or promote products derived from this software without
 *    prior written permission. For written permission, please contact
 *    openssl-core@openssl.org.
 *
 * 5. Products derived from this software may not be called "OpenSSL"
 *    nor may "OpenSSL" appear in their names without prior written
 *    permission of the OpenSSL Project.
 *
 * 6. Redistributions of any form whatsoever must retain the following
 *    acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
 *
 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 * ====================================================================
 *
 * This product includes cryptographic software written by Eric Young
 * (eay@cryptsoft.com).  This product includes software written by Tim
 * Hudson (tjh@cryptsoft.com).
 *
 */

 Original SSLeay License
 -----------------------

/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
 * All rights reserved.
 *
 * This package is an SSL implementation written
 * by Eric Young (eay@cryptsoft.com).
 * The implementation was written so as to conform with Netscapes SSL.
 *
 * This library is free for commercial and non-commercial use as long as
 * the following conditions are aheared to.  The following conditions
 * apply to all code found in this distribution, be it the RC4, RSA,
 * lhash, DES, etc., code; not just the SSL code.  The SSL documentation
 * included with this distribution is covered by the same copyright terms
 * except that the holder is Tim Hudson (tjh@cryptsoft.com).
 *
 * Copyright remains Eric Young's, and as such any Copyright notices in
 * the code are not to be removed.
 * If this package is used in a product, Eric Young should be given attribution
 * as the author of the parts of the library used.
 * This can be in the form of a textual message at program startup or
 * in documentation (online or textual) provided with the package.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this software
 *    must display the following acknowledgement:
 *    "This product includes cryptographic software written by
 *     Eric Young (eay@cryptsoft.com)"
 *    The word 'cryptographic' can be left out if the rouines from the library
 *    being used are not cryptographic related :-).
 * 4. If you include any Windows specific code (or a derivative thereof) from 
 *    the apps directory (application code) you must include an acknowledgement:
 *    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
 *
 * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * The licence and distribution terms for any publically available version or
 * derivative of this code cannot be changed.  i.e. this code cannot simply be
 * copied and put under another distribution licence
 * [including the GNU Public Licence.]
 */

